<HTML><HEAD><TITLE>open(++SourceSink, +Mode, ?Stream)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Stream I/O</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>open(++SourceSink, +Mode, ?Stream)</H1>
Opens the I/O source or sink SourceSink in mode Mode and associates it
with the stream identifier Stream.


<DL>
<DT><EM>SourceSink</EM></DT>
<DD>Atom, string or structure.
</DD>
<DT><EM>Mode</EM></DT>
<DD>One of the atoms read, write, update, append.
</DD>
<DT><EM>Stream</EM></DT>
<DD>Atom or variable.
</DD>
</DL>
<H2>Description</H2>
   This predicate opens an ECLiPSe I/O stream.

<P>
   The most common use is for opening files. In this case, SourceSink
   is a file name (atom or string).

<P>
   Mode is one of the following

<P>
<PRE>
    read         open for reading
    write        open for writing
    update       open for reading and writing
    append       open for writing at the end
</PRE>
   A file must already exist if it is to be opened in read mode.  A file
   opened in append mode is opened in write mode at the end of the file.
   If an existing file is opened in write mode, it is truncated to zero
   size, i.e. its previous content is lost.

<P>
   Stream is the identifier that is subsequently used to identify the
   stream.  This identifier is either a name (atom) provided by the user,
   or a system-generated identifier (when the user passes a free variable).

<P>
   If SourceSink is of the form string(InitialString), then a so-called
   string stream is opened.  A string stream is basically an in-memory
   file and its initial contents is the string InitialString.
   A string stream can be used like any other stream, i.e. it is possible
   to read, write and seek like on a true file.
   The current contents of a string stream can at any time be retrieved
   as a whole using get_stream_info(Stream, name, Contents).

<P>
   If SourceSink is of the form queue(InitialString), then a queue
   stream is opened. It behaves like a string that can be written at the
   end and read from the beginning.  Seeking is not allowed on queues.
   The current contents of a queue can at any time be retrieved as a
   whole using get_stream_info(Stream, name, Contents). Queues are
   considered to be at end-of-file while they are empty. 
   Queues can be configured to raise an event every time something
   is written to the previously empty queue (see open/4).

<P>
   If SourceSink is of the form fd(Integer), then the stream in opened
   onto an existing operating system file descriptor.

<P>
   Streams are not closed on backtracking through the call to open/3.

<P>

<H3>Modes and Determinism</H3><UL>
<LI>open(++, +, -) is det
<LI>open(++, +, +) is det
</UL>
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>File or Mode is not instantiated.
<DT><EM>(5) type error </EM>
<DD>File is not an atom, string or structure.
<DT><EM>(5) type error </EM>
<DD>Mode is not an atom.
<DT><EM>(5) type error </EM>
<DD>Stream is not an atom or a variable.
<DT><EM>(170) system interface error </EM>
<DD>The operating system cannot open the file.
<DT><EM>(192) illegal stream mode </EM>
<DD>Mode is an atom, but is not a valid mode.
</DL>
<H2>Examples</H2>
<PRE>
    [eclipse 1]: open(file1, write, S), write(S, foo), close(S).
    S = 6
    yes.
    [eclipse 2]: open(file1, update, S), read(S,X), write(S,bar), close(S).
    X = foo
    S = 6
    yes.
    [eclipse 3]: open(file1, append, S), write(S, baz), close(S).
    S = 6
    yes.
    [eclipse 4]: open(file1, read, mystr), read(mystr,X), close(mystr).
    X = foobarbaz
    yes.


    [eclipse 1]: open(string("foo"), update, S),
                 read(S,X), write(S,bar),
                 get_stream_info(S, name, Contents), close(S).
    X = foo
    Contents = "foobar"
    yes.

    [eclipse 1]: open(queue(""), update, S),
                 write(S, hello), read(S, X), close(S).
    X = hello
    yes.

    [eclipse 1]: event_create(writeln(my_event_handler), Event),
                 open(queue(""), write, S, [event(Event)]),
                 write(S, hello).
    my_event_handler
    S = 6
    yes.

Error:
       open(Var,update,s).      (Error 4).
       open(file1,Mode,s).      (Error 4).
       open(2,update,s).        (Error 5).
       open(file1,"str",s).     (Error 5).
       open(file1,update,9).    (Error 5).
       open(nonex,read,s).      (Error 170). % no such file
       open(file1,atom,s).      (Error 192). % no such mode



</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/iostream/at-2.html">at / 2</A>, <A HREF="../../kernel/iostream/at_eof-1.html">at_eof / 1</A>, <A HREF="../../kernel/iostream/current_stream-1.html">current_stream / 1</A>, <A HREF="../../kernel/iostream/get_stream_info-3.html">get_stream_info / 3</A>, <A HREF="../../kernel/iostream/open-4.html">open / 4</A>, <A HREF="../../kernel/iostream/pipe-2.html">pipe / 2</A>, <A HREF="../../kernel/iostream/seek-2.html">seek / 2</A>, <A HREF="../../kernel/iostream/select-3.html">select / 3</A>, <A HREF="../../kernel/iostream/stream_truncate-1.html">stream_truncate / 1</A>
</BODY></HTML>
